<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="UTF-8" />
<title>NASM - The Netwide Assembler</title>
<link href="nasmdoc.css" rel="stylesheet" type="text/css" />
<link href="local.css" rel="stylesheet" type="text/css" />
</head>
<body>
<ul class="navbar">
<li class="first"><a class="prev" href="nasmdoc5.html">Chapter 5</a></li>
<li><a class="next" href="nasmdoc7.html">Chapter 7</a></li>
<li><a class="toc" href="nasmdoc0.html">Contents</a></li>
<li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
</ul>
<div class="title">
<h1>NASM - The Netwide Assembler</h1>
<span class="subtitle">version 2.16.03</span>
</div>
<div class="contents"
>
<h2 id="chapter-6">Chapter 6: Standard Macro Packages</h2>
<p>The <code>%use</code> directive (see
<a href="nasmdoc4.html#section-4.8.4">section 4.8.4</a>) includes one of
the standard macro packages included with the NASM distribution and
compiled into the NASM binary. It operates like the <code>%include</code>
directive (see <a href="nasmdoc4.html#section-4.8.1">section 4.8.1</a>),
but the included contents is provided by NASM itself.</p>
<p>The names of standard macro packages are case insensitive and can be
quoted or not.</p>
<p>As of version 2.15, NASM has <code>%ifusable</code> and
<code>%ifusing</code> directives to help the user understand whether an
individual package available in this version of NASM
(<code>%ifusable</code>) or a particular package already loaded
(<code>%ifusing</code>).</p>
<h3 id="section-6.1">6.1 <code>altreg</code>: Alternate Register Names</h3>
<p>The <code>altreg</code> standard macro package provides alternate
register names. It provides numeric register names for all registers (not
just <code>R8</code>&ndash;<code>R15</code>), the Intel-defined aliases
<code>R8L</code>&ndash;<code>R15L</code> for the low bytes of register (as
opposed to the NASM/AMD standard names
<code>R8B</code>&ndash;<code>R15B</code>), and the names
<code>R0H</code>&ndash;<code>R3H</code> (by analogy with
<code>R0L</code>&ndash;<code>R3L</code>) for <code>AH</code>,
<code>CH</code>, <code>DH</code>, and <code>BH</code>.</p>
<p>Example use:</p>
<pre>
%use altreg 

proc: 
      mov r0l,r3h                    ; mov al,bh 
      ret
</pre>
<p>See also <a href="nasmdo12.html#section-12.1">section 12.1</a>.</p>
<h3 id="section-6.2">6.2 <code>smartalign</code>: Smart <code>ALIGN</code> Macro</h3>
<p>The <code>smartalign</code> standard macro package provides for an
<code>ALIGN</code> macro which is more powerful than the default (and
backwards-compatible) one (see
<a href="nasmdoc5.html#section-5.10.1">section 5.10.1</a>). When the
<code>smartalign</code> package is enabled, when <code>ALIGN</code> is used
without a second argument, NASM will generate a sequence of instructions
more efficient than a series of <code>NOP</code>. Furthermore, if the
padding exceeds a specific threshold, then NASM will generate a jump over
the entire padding sequence.</p>
<p>The specific instructions generated can be controlled with the new
<code>ALIGNMODE</code> macro. This macro takes two parameters: one mode,
and an optional jump threshold override. If (for any reason) you need to
turn off the jump completely just set jump threshold value to &ndash;1 (or
set it to <code>nojmp</code>). The following modes are possible:</p>
<ul>
<li>
<p><code>generic</code>: Works on all x86 CPUs and should have reasonable
performance. The default jump threshold is 8. This is the default.</p>
</li>
<li>
<p><code>nop</code>: Pad out with <code>NOP</code> instructions. The only
difference compared to the standard <code>ALIGN</code> macro is that NASM
can still jump over a large padding area. The default jump threshold is 16.</p>
</li>
<li>
<p><code>k7</code>: Optimize for the AMD K7 (Athlon/Althon XP). These
instructions should still work on all x86 CPUs. The default jump threshold
is 16.</p>
</li>
<li>
<p><code>k8</code>: Optimize for the AMD K8 (Opteron/Althon 64). These
instructions should still work on all x86 CPUs. The default jump threshold
is 16.</p>
</li>
<li>
<p><code>p6</code>: Optimize for Intel CPUs. This uses the long
<code>NOP</code> instructions first introduced in Pentium Pro. This is
incompatible with all CPUs of family 5 or lower, as well as some VIA CPUs
and several virtualization solutions. The default jump threshold is 16.</p>
</li>
</ul>
<p>The macro <code>__?ALIGNMODE?__</code> is defined to contain the current
alignment mode. A number of other macros beginning with
<code>__?ALIGN_</code> are used internally by this macro package.</p>
<h3 id="section-6.3">6.3 <code>fp</code>: Floating-point macros</h3>
<p>This packages contains the following floating-point convenience macros:</p>
<pre>
%define Inf             __?Infinity?__ 
%define NaN             __?QNaN?__ 
%define QNaN            __?QNaN?__ 
%define SNaN            __?SNaN?__ 

%define float8(x)       __?float8?__(x) 
%define float16(x)      __?float16?__(x) 
%define bfloat16(x)     __?bfloat16?__(x) 
%define float32(x)      __?float32?__(x) 
%define float64(x)      __?float64?__(x) 
%define float80m(x)     __?float80m?__(x) 
%define float80e(x)     __?float80e?__(x) 
%define float128l(x)    __?float128l?__(x) 
%define float128h(x)    __?float128h?__(x)
</pre>
<p>It also defines the a multi-line macro <code>bf16</code> that can be
used in a similar way to the <code>D</code><em>x</em> directives for the
other floating-point numbers:</p>
<pre>
     bf16 -3.1415, NaN, 2000.0, +Inf
</pre>
<h3 id="section-6.4">6.4 <code>ifunc</code>: Integer functions</h3>
<p>This package contains a set of macros which implement integer functions.
These are actually implemented as special operators, but are most
conveniently accessed via this macro package.</p>
<p>The macros provided are:</p>
<h4 id="section-6.4.1">6.4.1 Integer logarithms</h4>
<p>These functions calculate the integer logarithm base 2 of their
argument, considered as an unsigned integer. The only differences between
the functions is their respective behavior if the argument provided is not
a power of two.</p>
<p>The function <code>ilog2e()</code> (alias <code>ilog2()</code>)
generates an error if the argument is not a power of two.</p>
<p>The function <code>ilog2f()</code> rounds the argument down to the
nearest power of two; if the argument is zero it returns zero.</p>
<p>The function <code>ilog2c()</code> rounds the argument up to the nearest
power of two.</p>
<p>The functions <code>ilog2fw()</code> (alias <code>ilog2w()</code>) and
<code>ilog2cw()</code> generate a warning if the argument is not a power of
two, but otherwise behaves like <code>ilog2f()</code> and
<code>ilog2c()</code>, respectively.</p>
<h3 id="section-6.5">6.5 <code>masm</code>: MASM compatibility</h3>
<p>Since version 2.15, NASM has a MASM compatibility package with minimal
functionality, as intended to be used primarily with machine-generated
code. It does not include any "programmer-friendly" shortcuts, nor does it
in any way support ASSUME, symbol typing, or MASM-style structures.</p>
<p>To enable the package, use the directive:</p>
<p><code>%use masm</code></p>
<p>Currently, the MASM compatibility package emulates:</p>
<ul>
<li>
<p>The <code>FLAT</code> and <code>OFFSET</code> keywords are recognized
and ignored.</p>
</li>
<li>
<p>The <code>PTR</code> keyword signifies a memory reference, as if the
argument had been put in square brackets:</p>
<pre>
     mov eax,[foo]               ; memory reference 
     mov eax,dword ptr foo       ; memory reference 
     mov eax,dowrd ptr flat:foo  ; memory reference 
     mov eax,offset foo          ; address 
     mov eax,foo                 ; address (ambiguous syntax in MASM)
</pre>
</li>
<li>
<p>The <code>SEGMENT</code> ... <code>ENDS</code> syntax:</p>
<pre>
   segname SEGMENT 
       ... 
   segname ENDS
</pre>
</li>
<li>
<p>The <code>PROC</code> ... <code>ENDP</code> syntax:</p>
<pre>
   procname PROC [FAR] 
        ... 
   procname ENDP
</pre>
<p><code>PROC</code> will also define <code>RET</code> as a macro expanding
to either <code>RETF</code> if <code>FAR</code> is specified and
<code>RETN</code> otherwise. Any keyword after <code>PROC</code> other than
<code>FAR</code> is ignored.</p>
</li>
<li>
<p>The <code>TBYTE</code> keyword as an alias for <code>TWORD</code> (see
<a href="nasmdoc2.html#section-2.2.7">section 2.2.7</a>).</p>
</li>
<li>
<p>The <code>END</code> directive is ignored.</p>
</li>
<li>
<p>In 64-bit mode relative addressing is the default
(<code>DEFAULT REL</code>, see
<a href="nasmdoc7.html#section-7.2.1">section 7.2.1</a>).</p>
</li>
</ul>
<p>In addition, NASM now natively supports, regardless of whether this
package is used or not:</p>
<ul>
<li>
<p><code>?</code> and <code>DUP</code> syntax for the <code>DB</code> etc
data declaration directives (see
<a href="nasmdoc3.html#section-3.2.1">section 3.2.1</a>).</p>
</li>
<li>
<p><code>displacement[base+index]</code> syntax for memory operations,
instead of <code>[base+index+displacement]</code>.</p>
</li>
<li>
<p><code>seg:[addr]</code> instead of <code>[seg:addr]</code> syntax.</p>
</li>
<li>
<p>A pure offset can be given to <code>LEA</code> without square brackets:</p>
<pre>
     lea rax,[foo]               ; standard syntax 
     lea rax,foo                 ; also accepted
</pre>
</li>
</ul>
</div>
</body>
</html>
